home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Amiga Format CD 49
/
Amiga Format CD49 (2000-01-17)(Future Publishing)(GB)(Track 1 of 3)[!][issue 2000-02].iso
/
-websites-
/
whdload
/
docs
/
autodoc.txt
< prev
next >
Wrap
Text File
|
1999-12-06
|
77KB
|
1,997 lines
TABLE OF CONTENTS
WHDLoad/--Overview--
WHDLoad/resload_Abort
WHDLoad/resload_Control
WHDLoad/WHDLTAG_CBAF_SET
WHDLoad/WHDLTAG_CBSWITCH_SET
WHDLoad/WHDLTAG_IOERR_GET
WHDLoad/resload_CRC16
WHDLoad/resload_Decrunch
WHDLoad/resload_Delay
WHDLoad/resload_DeleteFile
WHDLoad/resload_DiskLoad
WHDLoad/resload_DiskLoadDev
WHDLoad/resload_FlushCache
WHDLoad/resload_GetFileSize
WHDLoad/resload_ListFiles
WHDLoad/resload_LoadFile
WHDLoad/resload_LoadFileDecrunch
WHDLoad/resload_LoadFileOffset
WHDLoad/resload_Patch
WHDLoad/resload_ProtectRead
WHDLoad/resload_ProtectReadWrite
WHDLoad/resload_ProtectRemove
WHDLoad/resload_ProtectSMC
WHDLoad/resload_ProtectWrite
WHDLoad/resload_Relocate
WHDLoad/resload_SaveFile
WHDLoad/resload_SaveFileOffset
WHDLoad/resload_SetCACR
WHDLoad/resload_SetCPU
WHDLoad.Slave/--Overview--
WHDLoad/--Overview--
The calling conventions for all functions are similar to the OS-Library-
concept. Parameters are provided in registers (except "resload_Abort"),
return codes comes in D0 (on some functions also in D1). After a function call
the registers D0-D1/A0-A1 are destroyed (D0,D1 may contain a returncode) they
are so called scratch registers. All other registers are preserved.
The base of the JMP tower in WHDLoad is similar to a LibraryBase. In
difference to the OS the base must not stand in A6 on calling a function, but
it is recommend to call all functions relative to a address register like
move.l (_resload,pc),a5
jsr (resload_Decrunch,a5)
The resload base is overgiven in A0 on calling the Slave first via
ws_GameLoader (see chapter WHDLoad.Slave/--Overview--).
some keywords used in this document:
Slave the file which contains the interface code
(see section WHDLoad.Slave/--Overview--)
BaseMem the memory which is used by the installed program, because
this memory is always Chip-memory and starts at address
$00000000, BaseMem is at the same time the size and the end
address of the used Chip-memory BaseMem is specified in the
Slave-structure in field "ws_BaseMemSize"
ExpMem is the expansions memory, a extra memory area which can
optionally requested by the Slave-structure, it may be
Chip- or Fast-memory dependedly on what is available
ExpMem is supported starting WHDLoad version 8
DiskImage a floppy disk stored as a file on hard disk
logical values used for returncodes (see dos/dos.i):
TRUE = -1 (or better <>0)
FALSE = 0
WHDLoad/resload_Abort
NAME
resload_Abort -- quit and return to operating system
SYNOPSIS
resload_Abort( success, primary, secondary)
(a7) (4,a7) (8,a7)
ULONG ULONG ULONG
FUNCTION
aborts and terminates the installed program and cause WHDLoad to
return to the operating system
INPUTS
success - the reason for aborting
one of TDREASON_#? defined in the include file "whdload.i"
depending on this value WHDLoad continues different
TDREASON_OK
a normal exit will performed
TDREASON_DEBUG
WHDLoad will create dump files (.whdl_dump, .whdl_memory,
.whdl_register) and exit
TDREASON_#? (except the above)
WHDLoad will show an requester which displays the reason
of aborting and requests the user to choose between
"Quit", "Restart" and "Make CoreDump"
primary - the primary return code further describing the reason of
aborting
TDREASON_DOSREAD, TDREASON_DOSWRITE, TDREASON_DOSLIST,
TDREASON_DISKLOAD, TDREASON_DISKLOADDEV, TDREASON_DELETEFILE
dos or trackdisk errorcode
TDREASON_DEBUG
program counter (so it can by written to the dump files)
TDREASON_OSEMUFAIL
name of the filed subsystem
TDREASON_OK, TDREASON_WRONGVER, TDREASON_REQ68020,
TDREASON_REQAGA, TDREASON_MUSTNTSC, TDREASON_MUSTPAL,
TDREASON_MUSTREG
unused (can be omitted)
secondary - the secondary return code further describing the reason of
aborting
TDREASON_DOSREAD, TDREASON_DOSWRITE, TDREASON_DELETEFILE
filename
TDREASON_DISKLOAD
disk number
TDREASON_DOSLIST
name of directory scanned
TDREASON_DEBUG
status register (so it can by written to the dump files)
TDREASON_OSEMUFAIL
error number, depending on the primary return code
TDREASON_OK, TDREASON_DISKLOADDEV, TDREASON_WRONGVER,
TDREASON_REQ68020, TDREASON_REQAGA, TDREASON_MUSTNTSC,
TDREASON_MUSTPAL, TDREASON_MUSTREG
unused (can be omitted)
EXAMPLE
to simply quit:
;primary and secondary wont be needed
move.l #TDREASON_OK,-(a7)
move.l (_resload,pc),a0
jmp (resload_Abort,a0)
to quit because reading of a file has failed:
move.l a0,-(a7) ;a0 = filename
move.l d0,-(a7) ;d0 = doserror code
move.l #TDREASON_DOSREAD,-(a7)
move.l (_resload,pc),-(a7)
add.l #resload_Abort,(a7)
rts
RESULT
nothing because WHDLoad will never return from this call
BUGS
NOTE
this routine is the only one which must be called via JMP and not JSR
because the parameters are located on the stack (this has the
advantage that if aborting because TDREASON_DEBUG all registers can be
preserved and written to the dump files by WHDLoad for further
diagnostics)
SEE ALSO
example Slave sources provided with the WHDLoad developer package
WHDLoad/resload_Control
NAME
resload_Control
SYNOPSIS
success = resload_Control(tags)
D0 A0
BOOL STRUCT
FUNCTION
control function of WHDLoad, allows to get and set various variables
concerning the software and hardware configuration and to control the
behavior of some WHDLoad operations
INPUTS
tags - pointer to a table of tagitems
the following items are currently supported:
WHDLTAG_ATTNFLAGS_GET - gets the AttnFlags describing the current
CPU, FPU and MMU, the returned value is
similar to execbase.AttnFlags but not equal
because WHDLoad uses some additional bits,
the Slave is only allowed to the use the
defines from the standard include file
"exec/execbase.i" for testing the returned
value
WHDLTAG_ECLOCKFREQ_GET - gets the EClockFrequency, which is the
frequency the custom chips operate on, the
value is taken from the execbase (see
standard include file "exec/execbase.i")
WHDLTAG_MONITOR_GET - gets the used monitor/video mode, the
returned value is one of NTSC_MONITOR_ID and
PAL_MONITOR_ID (defined in the standard
include file "graphics/modeid.i"), the
WHDLoad options PAL/S and NTSC/S are
affecting the monitor/video mode
WHDLTAG_BUTTONWAIT_GET - returns -1 if WHDLoad option ButtonWait/S
has been enabled, otherwise returns 0
WHDLTAG_CUSTOM1_GET
WHDLTAG_CUSTOM2_GET
WHDLTAG_CUSTOM3_GET
WHDLTAG_CUSTOM4_GET
WHDLTAG_CUSTOM5_GET - returns numerical value of WHDLoad option
Custom1/N .. Custom5/N
WHDLTAG_CBSWITCH_SET - sets a function which will be executed when
WHDLoad switches from the operating system
to the installed program (see section
WHDLoad/WHDLTAG_CBSWITCH_SET for further
informations)
WHDLTAG_CHIPREVBITS_GET - gets the ChipRevBits describing the current
custom chips, see standard include file
"graphics/gfxbase.i" for further explanation
WHDLTAG_IOERR_GET - gets the dos errorcode of the previously
executed resload function
WHDLTAG_CBAF_SET - sets a function which will be executed when
an access fault exception occurs (see
section WHDLoad/WHDLTAG_CBAF_SET for further
informations)
WHDLTAG_VERSION_GET - gets WHDLoad major version number
WHDLTAG_REVISION_GET - gets WHDLoad minor version number
WHDLTAG_BUILD_GET - gets WHDLoad build number
WHDLTAG_TIME_GET - gets current time and date, returned will be
a pointer to a filled whdload_time structure
which is decribed in the include file
"whdload.i"
EXAMPLE
check if current CPU is at least an MC68020:
...
clr.l -(a7) ;TAG_DONE
clr.l -(a7) ;data to fill
move.l #WHDLTAG_ATTNFLAGS_GET,-(a7)
move.l a7,a0
move.l (_resload,pc),a2
jsr (resload_Control,a2)
move.w (6,a7),d0 ;D0 = AttnFlags
lea (12,a7),a7 ;restore sp
btst #AFB_68020,d0
beq .no68020
...
get video mode and CPU:
...
lea (_tags,pc),a0
move.l (_resload,pc),a2
jsr (resload_Control,a2)
move.l (_mon,pc),d0 ;D0 = video mode
cmp.l #NTSC_MONITOR_ID,d0
beq .ntsc
...
_tags dc.l WHDLTAG_MONITOR_GET
_mon dc.l 0
dc.l WHDLTAG_ATTNFLAGS_GET
dc.w 0 ;padding
_attn dc.w 0
dc.l 0 ;TAG_DONE
RESULT
success is true if all items in the taglist has been successfully
processed
BUGS
NOTE
requires ws_Version >= 5
SEE ALSO
WHDLoad/WHDLTAG_CBAF_SET
NAME
WHDLTAG_CBAF_SET
SYNOPSIS
to be used with resload_Control
cont, adr, data = CBAF(mode, size, pc, adr, data)
D0 A1 A2 D0 D1 A0 A1 A2
LONG APTR APTR LONG LONG APTR APTR APTR
FUNCTION
using this tag a function can be set which will executed when an
access fault exception occurs which is not handled by WHDLoad itself,
it may be used to locate specific accesses in conjunction with
resload_Protect and to walk around invalid accesses during the
development process
using this tag all access faults can be catched except:
- instruction stream faults
- faults caused by WHDLoad's blitwait and blitsize checks
the routine set using this tag must not change any registers except
the ones holding a return value, the routine must return via RTS, on
entering the routine all interrupts are disabled (sr=$27xx)
INPUTS
mode - transfer mode of the faulted access
0 - read
1 - modify (only 68040/060)
2 - write
size - operand size of the attempted access
1 - Byte
2 - Word
4 - LongWord
pc - program counter of the instruction which has faulted
(warning this may sometimes already the instruction after the
one which has faulted, read the appropriate microprocessor user
manual for further informations)
adr - the address which has been attempted to access
data - valid only on write operations, the given memory address
contains the data which has been tried to write
RESULT
cont - how to continue
0 - terminate, WHDLoad will show a requester notifying the
access fault
1 - proceed, the faulted access will be emulated by the
handler inside great WHDLoad
adr - in case of cont=proceed the address which will be accessed
data - in case of cont=proceed and mode=write a pointer to the data
which will be written (only 68030)
EXAMPLE
if you want to get informed at which point the installed program
writes the value 42 to the address $BABE, use the following code:
...
clr.l -(a7) ;TAG_DONE
pea (_af,pc) ;function
move.l #WHDLTAG_CBAF_SET,-(a7)
move.l a7,a0
move.l (_resload,pc),a2
jsr (resload_Control,a2)
lea (12,a7),a7 ;restore sp
moveq #2,d0
lea ($BABE),a0
jsr (resload_ProtectWrite,a2) ;protect area
...
_af cmp.l #$BABE,a1 ;correct address ?
bne .term
cmp.w #2,d1 ;size
bne .term
cmp.w #42,(a2)
beq .term
moveq #1,d0 ;proceed
rts
.term moveq #0,d0 ;terminate
rts
EXAMPLE
if want you to redirect an access to $24 to the address $300, use the
following code:
...
clr.l -(a7) ;TAG_DONE
pea (_af,pc) ;function
move.l #WHDLTAG_CBAF_SET,-(a7)
move.l a7,a0
move.l (_resload,pc),a2
jsr (resload_Control,a2)
lea (12,a7),a7 ;restore sp
moveq #4,d0
lea ($24),a0
jsr (resload_ProtectWrite,a2) ;protect area
...
_af cmp.l #$24,a1 ;correct address ?
bne .term
lea ($300),a1
moveq #1,d0 ;proceed
rts
.term moveq #0,d0 ;terminate
rts
BUGS
currently only 68030 is supported
NOTE
requires ws_Version >= 9
MUST not be used in public releases, use for development process only
SEE ALSO
resload_Control
WHDLoad/WHDLTAG_CBSWITCH_SET
NAME
WHDLTAG_CBSWITCH_SET
SYNOPSIS
to be used with resload_Control
CBSWITCH()
FUNCTION
using this tag a routine can be set which will executed each time
WHDLoad switches from the operating system to the installed program
such a routine is sometimes necessary because during the switch
between the installed program and the operating system some hardware
registers are modified by the operating system
known registers to be modified are cop2lc, bltafwm and bltalwm, maybe
there are more of them
the routine must not change any registers, must not use any stack and
has to return via "jmp (a0)", at execution time of the routine all
interrupts and dma's are disabled and the memory setup of the
installed program is active
INPUTS
pointer to the routine to execute during switch, a value equal 0
disables the execution of a routine
EXAMPLE
...
clr.l -(a7) ;TAG_DONE
pea (_cbswitch,pc) ;function
move.l #WHDLTAG_CBSWITCH_SET,-(a7)
move.l a7,a0
move.l (_resload,pc),a2
jsr (resload_Control,a2)
lea (12,a7),a7 ;restore sp
...
_cbswitch move.l (_c2,pc),(_custom+cop2lc)
jmp (a0)
_cb2 dc.l $10e80
RESULT
none
BUGS
NOTE
requires ws_Version >= 7
SEE ALSO
resload_Control
WHDLoad/WHDLTAG_IOERR_GET
NAME
WHDLTAG_IOERR_GET
SYNOPSIS
to be used with resload_Control
FUNCTION
this tag can be used to get the dos errorcode of the last called
resload function, all resload functions except resload_Control will
set/reset this error code
two resload functions are special in that way:
resload_GetFileSize
if a file with the specified name cannot be opened via
dos.Open, the error code will be set to the value returned
from dos.IoErr, so the error code may contain values like
ERROR_OBJECT_NOT_FOUND, ERROR_OBJECT_WRONG_TYPE,
ERROR_READ_PROTECTED or similar stuff from dos/dos.i
the errorcode can be used to distinguish between a file with
size of 0 and a nonexistent file
resload_ListFiles
if the specified buffer to fill is not large enough to hold
all filenames from the scanned directory, the error code will
be set to ERROR_NO_FREE_STORE
INPUTS
none
EXAMPLE
...
clr.l -(a7) ;TAG_DONE
clr.l -(a7) ;data to fill
move.l #WHDLTAG_IOERR_GET,-(a7)
move.l a7,a0
move.l (_resload,pc),a2
jsr (resload_Control,a2)
move.l (4,a7),d0 ;D0 = IoErr
lea (12,a7),a7 ;restore sp
...
RESULT
none
BUGS
NOTE
requires ws_Version >= 8
SEE ALSO
resload_Control, resload_GetFileSize, resload_ListFiles
WHDLoad/resload_CRC16
NAME
resload_CRC16 -- calculate ANSI conform 16 bit CRC checksum
SYNOPSIS
checksum = resload_CRC16(length,address)
D0 D0 A0
UWORD ULONG APTR
FUNCTION
calculate ANSI conform 16 bit CRC checksum
mostly used to difference between various program versions
INPUTS
length - length of area to calculate over
address - pointer to area
EXAMPLE
...
lea $1000,a0 ;at address $1000
move.l #256,d0 ;upto address $1100
move.l (_resload,pc),a2
jsr (resload_CRC16,a2)
cmp.w #$f2b7,d0
bne .false_version
...
RESULT
checksum - 16 bit crc
BUGS
NOTE
requires ws_Version >= 3
SEE ALSO
WHDLoad/resload_Decrunch
NAME
resload_Decrunch -- uncompress data in memory
SYNOPSIS
size = resload_Decrunch(source, destination)
D0 A0 A1
ULONG APTR APTR
FUNCTION
unpack compressed data in memory, known compressed data formats are
RNC1, RNC2, IMP! and ATN!
the function first checks if the data source points to is a known
compressed format, if not it returns with size=0, else the data will
be unpacked to the destination and the size of the decompressed data
is returned
source and destination can be equal, in that case the packed data will
be overwritten
RNC1: rob northen compressor - emphasis on packed size, supported is
the old and the new format, both formats using the same id but
different file formats and compressing algorithms, the
function uses some heuristic checks to determinate the correct
format, the decompressor for the new common format is highly
optimized and contains a routine for 68000/010 and one for
68020+, on 68060 it is faster than the IMP! decompressor!
RNC2: rob northen compressor - emphasis on unpacking speed, the
fastest supported decompressor
IMP!: imploder (FImp), the packed data data must not overlap the
destinaion for unpacking but the destination must be equal the
source or outside the source data, in difference to the
original explode routine resload_Decrunch does not destroy the
source data (if source is not equal destination)
ATN!: identical to IMP! only id is different
all decompressing routines has been modified to not modify the
registers A5 and A6 and to use nearly no stack space
all decompressing routines performing a check if the decompression was
successful, on a failure the installed program will be terminated and
WHDLoad will display a message concerning this
INPUTS
source - address of source in memory
destination - address of destination in memory (can be equal to source)
EXAMPLE
RESULT
size - the size of the uncompressed data or 0 if is not compressed
with a known format
BUGS
NOTE
the routine performs automatically a resload_FlushCache before
returning
SEE ALSO
resload_LoadFileDecrunch
WHDLoad/resload_Delay
NAME
resload_Delay -- wait some time
SYNOPSIS
resload_Delay(time)
D0
ULONG
FUNCTION
wait the specified time or until a button is pressed, all possible
buttons (LMB, MMB, RMB) of both controllers (port 0/1) are checked,
after the time runs out or a button is pressed the function waits
until all buttons has been released
the wait routine is based on the raster beam, but checks the current
display and therefore waits the correct time on PAL and NTSC
INPUTS
time - time to wait in 1/10 seconds
EXAMPLE
...
moveq #30,d0 ;3 seconds
move.l (_resload,pc),a2
jsr (resload_Delay,a2)
...
RESULT
nothing, all registers are preserved
BUGS
NOTE
in difference to most others resload_#? function this routine is
granted to preserve all registers
requires ws_Version >= 8
SEE ALSO
WHDLoad/resload_DeleteFile
NAME
resload_Delete -- delete file
SYNOPSIS
success,errorcode = resload_DeleteFile(name)
D0 D1 A0
BOOL ULONG CPTR
FUNCTION
deletes the file or directory with the specified name
INPUTS
name - name of the file/directory to delete
EXAMPLE
...
lea (_name,pc),a0
move.l (_resload,pc),a2
jsr (resload_DeleteFile,a2)
...
_name dc.b "C:WHDLoad",0
RESULT
success - TRUE on success
errorcode - 0 on success
otherwise a dos-errorcode from dos.IoErr()
if WHDLF_NoError is set, the function only returns on success
BUGS
NOTE
requires ws_Version >= 8
SEE ALSO
WHDLoad/resload_DiskLoad
NAME
resload_DiskLoad -- load part from a diskimage
SYNOPSIS
success,errorcode = resload_DiskLoad(offset,size,diskno,dest)
D0 D1 D0 D1 D2 A0
BOOL ULONG ULONG ULONG UBYTE APTR
FUNCTION
load part from a diskimage
INPUTS
offset - offset in diskimage (relative to the beginning)
size - amount of bytes to read
diskno - disk number
dest - destination address
EXAMPLE
...
move.l #880*512,d0 ;from block 880
move.l #2*512,d1 ;2 blocks
moveq #1,d2 ;disk 1
lea $80000,a0 ;destination
move.l (_resload,pc),a2
jsr (resload_LoadDisk,a2)
...
RESULT
success - TRUE on success
errorcode - 0 on success
otherwise a dos-errorcode from dos.IoErr()
if WHDLF_NoError is set, the function only returns on success
BUGS
NOTE
the name of the disk images must be "disk." followed by the disk
number (i.e. "Disk.1")
the size of the diskimages is variable, an attempt to read data
outside the disk image will result in a seek error
the routine performs automatically a resload_FlushCache before
returning
SEE ALSO
resload_LoadFileOffset
WHDLoad/resload_DiskLoadDev
NAME
resload_DiskLoadDev -- load part from a floppy disk
SYNOPSIS
success,errorcode = resload_DiskLoadDev(offset, size, dest, tags)
D0 D1 D0 D1 A0 A1
BOOL ULONG ULONG ULONG UBYTE STRUCT
FUNCTION
load a given amount of bytes from a floppy like device
INPUTS
offset - offset on the disk (relative to the beginning)
size - amount of bytes to read (at the moment this must be a
multiple of 512 bytes)
dest - destination address (at the moment this must be aligned
to 512 bytes)
tags - pointer to a taglist (at the moment there are no valid
tags, so this must be NULL)
EXAMPLE
...
move.l #880*512,d0 ;from block 880
move.l #2*512,d1 ;2 blocks
lea $80000,a0 ;destination
sub.l a1,a1 ;tag list
move.l (_resload,pc),a2
jsr (resload_LoadDisk,a2)
...
RESULT
success - TRUE on success
errorcode - 0 on success
otherwise a trackdisk errorcode
if WHDLF_NoError is set, the function only returns on success
BUGS
NOTE
requires ws_Version >= 2
at the moment all (size, address) must be aligned to 512 bytes due
restrictions of trackdisk.device
the routine performs automatically a resload_FlushCache before
returning
SEE ALSO
WHDLoad/resload_FlushCache
NAME
resload_FluchCache -- clear CPU caches
SYNOPSIS
resload_FlushCache()
FUNCTION
clear all CPU caches
INPUTS
EXAMPLE
RESULT
BUGS
NOTE
in difference to most others resload_#? function this routine is
granted to preserve all registers
it is safe to call this routine from User or Supervisor mode and
independend from the actual CPU type (also on 68000/010)
it uses the CACR on 68020/030 and a "cpusha bc" on 68040/060
SEE ALSO
resload_SetCPU
WHDLoad/resload_GetFileSize
NAME
resload_GetFileSize -- get size of a file
SYNOPSIS
size = resload_GetFileSize(name)
D0 A0
ULONG CPTR
FUNCTION
get size of a file, or check if a file exists
to distinguish between a file with a size of 0 and an nonexisting
file the tag WHDLTAG_IOERR_GET must be used in conjunction with
resload_Control
INPUTS
name - name of the file to get size from
EXAMPLE
...
lea (_filename,pc),a0
move.l (_resload,pc),a2
jsr (resload_GetFileSize,a2)
tst.l d0
bne .file_not_exist
...
RESULT
size - the size of the file, 0 if does not exist
BUGS
NOTE
this routine returns the filesize obtained by the filesystem, if the
file is compressed and is loaded later via resload_LoadFileDecrunch
the loaded filesize will differ!
SEE ALSO
resload_Control, resload_LoadFile, resload_LoadFileDecrunch
WHDLoad/resload_ListFiles
NAME
resload_ListFiles -- list filenames of a directory
SYNOPSIS
amount,errorcode = resload_ListFiles(buffersize, name, buffer)
D0 D1 D0 A0 A1
ULONG ULONG ULONG CPTR APTR
FUNCTION
writes the names of all files in the specified directory to the
buffer, the file names are separated with a $0 character
only files are listed, directories are skipped
if the buffer to fill is not large enough to hold all file names the
routine fills it as far as possible, the tag WHDLTAG_IOERR_GET in
conjunction with resload_Control can be used to check if all file
names have fit into the buffer
INPUTS
buffersize - the size of the buffer
name - the name of the directory to scan
buffer - pointer to the buffer (the buffer must be located inside
the Slave)
EXAMPLE
...
move.l #_bufend-_buf,d0
lea (_savepath,pc),a0
lea (_buf,pc),a1
move.l (_resload,pc),a2
jsr (resload_ListFiles,a2)
...
_buf ds.b 1000
_bufend
_savepath dc.b "/save",0 ;this must be a relative path!
RESULT
amount - amount of listed files in the buffer
errorcode - 0 on success
otherwise a dos-errorcode from dos.IoErr()
if WHDLF_NoError is set, the function only returns on success
BUGS
NOTE
SEE ALSO
resload_Control
WHDLoad/resload_LoadFile
NAME
resload_LoadFile -- load file into memory
SYNOPSIS
length,errorcode = resload_LoadFile(name, address)
D0 D1 A0 A1
ULONG ULONG CPTR APTR
FUNCTION
load file to the specified memory address
INPUTS
name - name of the file to load
address - memory address to load the file on
EXAMPLE
...
lea (_filename),a0 ;name
lea $1000.w,a1 ;destination
move.l (_resload,pc),a2
jsr (resload_LoadFile,a2)
...
RESULT
length - the size of the loaded file, or 0 on error
errorcode - 0 on success
otherwise a dos-errorcode from dos.IoErr()
if WHDLF_NoError is set, the function only returns on success
BUGS
NOTE
the routine performs automatically a resload_FlushCache before
returning
SEE ALSO
resload_LoadFileDecrunch, resload_LoadFileOffset
WHDLoad/resload_LoadFileDecrunch
NAME
resload_LoadFileDecrunch -- load file and uncompress
SYNOPSIS
length,errorcode = resload_LoadFileDecrunch(name, address)
D0 D1 A0 A1
ULONG ULONG CPTR APTR
FUNCTION
loads the specified file into memory and unpack it if it is in a
supported compressed data format
using this routine instead of resload_LoadFile easily allows it to add
support for compressed data files to a installed program, the
decompression is absolutely transparent, so the installed program will
not detect if the files loaded are compressed on disk or not, the only
thing which must be considered is that files that are written using
resload_SaveFileOffset or loaded via resload_LoadFileOffset must not
be compressed
INPUTS
name - name of file to load
address - memory address to load the file on
EXAMPLE
...
lea (_filename),a0 ;name
lea $1000.w,a1 ;destination
move.l (_resload,pc),a2
jsr (resload_LoadFileDecrunch,a2)
...
RESULT
length - the size of the loaded file
if an error occurs this is 0
errorcode - 0 on success
otherwise a dos-errorcode from dos.IoErr()
if WHDLF_NoError is set, the function only returns on success
BUGS
NOTE
the routine performs automatically a resload_FlushCache before
returning
SEE ALSO
resload_Decrunch, resload_LoadFile, resload_LoadFileOffset,
resload_SaveFile, resload_SaveFileOffset
WHDLoad/resload_LoadFileOffset
NAME
resload_LoadFileOffset -- load data inside a file to memory
SYNOPSIS
success,error = resload_LoadFileOffset(size, offset, name, address)
D0 D1 D0 D1 A0 A1
BOOL ULONG ULONG ULONG CPTR APTR
FUNCTION
load a part of a file into memory, the part of the file is specified
by an offset in the file and a byte count to read, the routine is
nearly identical to resload_DiskLoad but instead of specifying the
number of the disk to read from a filename is used to select the file
INPUTS
size - amount of bytes to read
offset - offset in the file
name - name of file
address - memory address to load the file on
EXAMPLE
...
move.l #512,d0 ;size
move.l #$4000,d1 ;offset
lea (_save,pc),a0 ;name
lea $5ac20,a1 ;source
move.l (_resload,pc),a2
jsr (resload_LoadFileOffset,a2)
...
_save dc.b "saved",0
RESULT
success - TRUE on success
errorcode - 0 on success
otherwise a dos-errorcode from dos.IoErr()
if WHDLF_NoError is set, the function only returns on success
BUGS
NOTE
the routine performs automatically a resload_FlushCache before
returning
requires ws_Version >= 6
SEE ALSO
resload_DiskLoad, resload_LoadFile
WHDLoad/resload_Patch
NAME
resload_Patch -- apply patchlist
SYNOPSIS
resload_Patch(patchlist, destination)
A0 A1
APTR APTR
FUNCTION
modify memory using commands from a specified patch list,
to make an installed program working under WHDLoad it must be patched,
that means the program must be modified so that it will load data via
WHDLoad instead of using its own loader routines, often also various
other things must be changed to make it working
the modifying of the installed program can be done using this routine,
a patch list will be build by using macros from the include file
"whdpatch.i", each entry in the patchlist specifies a command to
perform, an address to apply the command on and optional extra data,
resload_Patch is especially useful if the memory to modify is located
in the ExpMem and therefore the destination address in only know at
runtime and not at creation time of the Slave
INPUTS
patchlist - list of commands describing the patches to apply
destination - address of memory region to patch
EXAMPLE
...
lea (_pl,pc),a0 ;patchlist
move.l (_expmem,pc),a1 ;destination
move.l (_resload,pc),a2
jsr (resload_Patch,a2)
...
_pl PL_START
PL_P $560,_loadfile ;the loading routine
PL_R $2046 ;copylock
PL_END
RESULT
BUGS
NOTE
the routine performs automatically a resload_FlushCache before
returning
requires ws_Version >= 10
SEE ALSO
WHDLoad/resload_ProtectRead
NAME
resload_ProtectRead -- mark memory as read protected
SYNOPSIS
resload_ProtectRead(length, address)
D0 A0
ULONG APTR
FUNCTION
protect the specified memory against reading by the processor
the memory to protect must be located inside BaseMem or ExpMem
INPUTS
length - size of the memory area to protected
address - start address of the memory area to protected
EXAMPLE
...
moveq #4,d0 ;one longword
lea $4070,a0 ;address
move.l (_resload,pc),a2
jsr (resload_ProtectRead,a2)
...
RESULT
a "Exception 'Access Fault'" WHDLoad requester if the protected memory
is accessed
BUGS
the amount of protected areas is currently limited to 16,
the page where the SSP points to must not be protected, because if a
Access Fault occurs the CPU will be unable in that case to write the
exception stackframe, only reset will recover from the resulting
Double Bus Fault
limitations on MC68020+MC68851:
this hardware is currently not supported
limitations on MC68030:
- 3-byte transfers are not supported (occuring on misaligned
longword accesses to page boundaries eg. "tst.l $fff" (assumed
4KByte page size))
- locked accesses (tas/cas/cas2) are not supported
limitations on MC68040:
this hardware is currently not supported
limitations on MC68060:
- misaligned access are not supported (occuring on accesses trough a
page boundary, for example "tst.l ($ffe)" (assumed 4KByte page
size))
- locked accesses (tas/cas) are not supported
- instructions which are located on a protected page and access the
supervisor portion of the status register will be executed wrong
(these instructions will always see the trace bit as 1 and the
interrupt level as 7, any modification of the status register
supervisor portion will be without effect)
- movem instruction may access a protected area without creating a
Access Fault exception (only the first bus cycle of the excution
unit will be verified for matching a protected area)
- move16 and double precision operations (FPU) are unsupported
- a "move (mem),(mem)" with overlapping source and destination
address which generates an Access Fault because Misalignment
will be executed wrong, for example "move.l ($ffc),($ffe)" where
page $1000..$1fff is protected and memory before execution
contains ($ffc)=$11112222,($1000)=$33334444, after execution
$1000 contains $11114444 and not $22224444)
unsupported accesses will result in a "Exception 'Access Fault'"
WHDLoad requester
NOTE
requires ws_Version >= 6
the MMU must be in use by WHDLoad, otherwise you will get WHDLoad
requester "Unacceptible Arguments".
only accesses to the user and supervisor data stream are affected
(this means not affected are: CPU space accesses (eg getting values
from the vector table) and instruction stream accesses)
SEE ALSO
resload_ProtectReadWrite, resload_ProtectWrite, resload_ProtectRemove
WHDLoad/resload_ProtectReadWrite
NAME
resload_ProtectReadWrite -- mark memory as read and write protected
SYNOPSIS
resload_ProtectReadWrite(length, address)
D0 A0
ULONG APTR
FUNCTION
protect the specified memory against reading and writing by the
processor
the memory to protect must be located inside BaseMem or ExpMem
INPUTS
length - size of the memory area to protected
address - start address of the memory area to protected
EXAMPLE
...
moveq #4,d0 ;one longword
lea $64,a0 ;address
move.l (_resload,pc),a2
jsr (resload_ProtectReadWrite,a2)
...
RESULT
a "Exception 'Access Fault'" WHDLoad requester if the protected memory
is accessed
BUGS
the amount of protected areas is currently limited to 16,
the page where the SSP points to must not be protected, because if a
Access Fault occurs the CPU will be unable in that case to write the
exception stackframe, only reset will recover from the resulting
Double Bus Fault
limitations on MC68020+MC68851:
this hardware is currently not supported
limitations on MC68030:
- 3-byte transfers are not supported (occuring on misaligned
longword accesses to page boundaries eg. "tst.l $fff" (assumed
4KByte page size))
- locked accesses (tas/cas/cas2) are not supported
limitations on MC68040:
this hardware is currently not supported
limitations on MC68060:
- misaligned access are not supported (occuring on accesses trough a
page boundary, for example "tst.l ($ffe)" (assumed 4KByte page
size))
- locked accesses (tas/cas) are not supported
- instructions which are located on a protected page and access the
supervisor portion of the status register will be executed wrong
(these instructions will always see the trace bit as 1 and the
interrupt level as 7, any modification of the status register
supervisor portion will be without effect)
- movem instruction may access a protected area without creating a
Access Fault exception (only the first bus cycle of the excution
unit will be verified for matching a protected area)
- move16 and double precision operations (FPU) are unsupported
- a "move (mem),(mem)" with overlapping source and destination
address which generates an Access Fault because Misalignment
will be executed wrong, for example "move.l ($ffc),($ffe)" where
page $1000..$1fff is protected and memory before execution
contains ($ffc)=$11112222,($1000)=$33334444, after execution
$1000 contains $11114444 and not $22224444)
unsupported accesses will result in a "Exception 'Access Fault'"
WHDLoad requester
NOTE
requires ws_Version >= 6
the MMU must be in use by WHDLoad, otherwise you will get WHDLoad
requester "Unacceptible Arguments".
only accesses to the user and supervisor data stream are affected
(this means not affected are: CPU space accesses (eg getting values
from the vector table) and instruction stream accesses)
SEE ALSO
resload_ProtectRead, resload_ProtectWrite, resload_ProtectRemove
WHDLoad/resload_ProtectRemove
NAME
resload_ProtectRemove -- remove protection from memory area
SYNOPSIS
resload_ProtectRemove(length, address)
D0 A0
ULONG APTR
FUNCTION
remove a previously created protection
the specified area must exactly match the previously protected area
INPUTS
length - size of the memory area to protected
address - start address of the memory area to protected
EXAMPLE
...
moveq #4,d0 ;one longword
lea $64,a0 ;address
move.l (_resload,pc),a2
jsr (resload_ProtectRemove,a2)
...
RESULT
BUGS
NOTE
requires ws_Version >= 6
SEE ALSO
resload_ProtectRead, resload_ProtectWrite, resload_ProtectWrite
WHDLoad/resload_ProtectSMC
NAME
resload_ProtectSMC -- detect self modifying code
SYNOPSIS
resload_ProtectSMC(length, address)
D0 A0
ULONG APTR
FUNCTION
Enables automatically detection of self modifying code (SMC) in the
selected area. The selected area will be write protected using the
resload_ProtectWrite mechanism, additional the trace mode will be
activated and a special handler for trace exceptions installed.
Each write access to the selected area will be logged to a private
memory location. On each instruction executed inside the selected
memory the trace handler verifies, if the instruction has been
previosly modified. If an executed instruction has been altered
the installed program will be terminated and WHDLoad will show an
requester informing about the SMC-detection.
To determinate the size of instructions a table is used. This table
contains the opcode size in words depending on the first instruction
word. If the trace exception handler encounters a instruction with
unknown size WHDLoad aborts with an "Internal Error #3". The reason
for this maybe an illegal instruction, an instruction available only
in higher processors than 68000 or an incompleteness of the internal
instruction size table (IST). To aid this, during the initialisation
of this function WHDLoad searches first for an external IST. This
must be located in the same directory where the WHDLoad executable
resides and is searched as "PROGDIR:WHDLoad.IST". If there is no
external IST the internal one is used. The source of the internal
IST is included in source representation and can be used to build a
external IST. If you encounter missing 68000 instructions in the
current IST you are demand to inform the author of WHDLoad to
include appropriate extensions in the next WHDLoad release.
Due the large exception overhead the execution speed in the selected
area will strongly slow down. To improve performance it is therefore
recommend to relocate the SSP to a Fast-Memory location using
ws_ExpMem and appropriate initialistion and modification of the
installed program if required.
To maximize performance during the initialisation of this function
the BaseMem area will be set to NC, the ExpMem and Slave to CB and
all caches will be enabled (resload_SetCPU).
Because Resload functions cannot be executed in trace mode, the
trace must disabled before and enabled after calling any Resload
function following the SMC-detection has been setup (see example).
INPUTS
length - size of the memory area to protected
address - start address of the memory area to protected
the area to protect must be located inside the BaseMem or ExpMem
EXAMPLE
enable SMC-detection for the area $10000..$3e000:
...
move.l #$2e000,d0 ;one longword
lea $10000,a0 ;address
move.l (_resload,pc),a2
jsr (resload_ProtectSMC,a2)
...
load data after enabling the SMC-detection (assumed all time in
supervisor mode!):
...
move sr,d3 ;save sr
move #$2000,sr ;disable trace mode
move.l (_resload,pc),a2
jsr (resload_DiskLoad,a2)
move d3,sr ;restore sr
...
RESULT
BUGS
Currently supported is only 68030 and 68060. For limitations and
restrictions regarding the MMU related part of operation see the BUGS
section of resload_ProtectWrite.
You must not protect the page where the SSP points to, if you do so
an Double Bus Fault will occure because the CPU will be unable to
write the exception stackframe, only reset will recover from a Double
Bus Fault
NOTE
requires ws_Version >= 10
the MMU must be in use by WHDLoad, otherwise you will get WHDLoad
requester "Unacceptible Arguments"
there must no resload_Protect* active at the same time
SEE ALSO
resload_ProtectWrite, resload_SetCPU
WHDLoad/resload_ProtectWrite
NAME
resload_ProtectWrite -- mark memory as write protected
SYNOPSIS
resload_ProtectWrite(length, address)
D0 A0
ULONG APTR
FUNCTION
protect the selected area against writing by the processor
the area to protect must be located inside BaseMem or ExpMem
INPUTS
length - size of the memory area to protected
address - start address of the memory area to protected
EXAMPLE
...
moveq #4,d0 ;one longword
lea $64,a0 ;address
move.l (_resload,pc),a2
jsr (resload_ProtectWrite,a2)
...
RESULT
BUGS
the amount of protected areas is currently limited to 16,
the page where the SSP points to must not be protected, because if a
Access Fault occurs the CPU will be unable in that case to write the
exception stackframe, only reset will recover from the resulting
Double Bus Fault
limitations on MC68020+MC68851:
this hardware is currently not supported
limitations on MC68030:
- 3-byte transfers are not supported (occuring on misaligned
longword accesses to page boundaries eg. "tst.l $fff" (assumed
4KByte page size))
- locked accesses (tas/cas/cas2) are not supported
limitations on MC68040:
this hardware is currently not supported
limitations on MC68060:
- misaligned access are not supported (occuring on accesses trough a
page boundary, for example "tst.l ($ffe)" (assumed 4KByte page
size))
- locked accesses (tas/cas) are not supported
- instructions which are located on a protected page and access the
supervisor portion of the status register will be executed wrong
(these instructions will always see the trace bit as 1 and the
interrupt level as 7, any modification of the status register
supervisor portion will be without effect)
- movem instruction may access a protected area without creating a
Access Fault exception (only the first bus cycle of the excution
unit will be verified for matching a protected area)
- move16 and double precision operations (FPU) are unsupported
- a "move (mem),(mem)" with overlapping source and destination
address which generates an Access Fault because Misalignment
will be executed wrong, for example "move.l ($ffc),($ffe)" where
page $1000..$1fff is protected and memory before execution
contains ($ffc)=$11112222,($1000)=$33334444, after execution
$1000 contains $11114444 and not $22224444)
unsupported accesses will result in a "Exception 'Access Fault'"
WHDLoad requester
NOTE
requires ws_Version >= 6
the MMU must be in use by WHDLoad, otherwise you will get WHDLoad
requester "Unacceptible Arguments".
only accesses to the user and supervisor data stream are affected
(this means not affected are: CPU space accesses (eg getting values
from the vector table) and instruction stream accesses)
SEE ALSO
resload_ProtectRead, resload_ProtectReadWrite, resload_ProtectRemove
WHDLoad/resload_Relocate
NAME
resload_Relocate -- relocate AmigaDOS executable
SYNOPSIS
size = resload_Relocate(address, tags)
D0 A0 A1
ULONG APTR STRUCT
FUNCTION
relocate an standard AmigaDOS executable in memory
INPUTS
address - the start address of the executable in memory, this is the
source and also the destination address, i.e.
resload_Relocate will relocates the executable over itself
(a multi pass technique is used)
tags - currently there are no tags so this must be set to NULL
EXAMPLE
...
lea (_main,pc),a0 ;name
lea $400,a3 ;A3 = address for program
move.l a3,a1 ;destination
move.l (_resload,pc),a2
jsr (resload_LoadFileDecrunch,a2)
move.l a3,a0 ;address
sub.l a1,a1 ;tags
jsr (resload_Relocate,a2)
...
jmp (a3) ;start the program
...
_main dc.b "main-program",0
RESULT
size - size of the relocated executable
(this may be more or less than the size of the executable file,
depending on BSS hunks contained in the executable)
BUGS
the routine supports all hunks supported by Kickstart 1.3 except
OVERLAY, anyway it is only tested with a limited amount of
executables, so please report any problems or bugs
NOTE
the function uses stack for variables, the amount depends on the
number of hunks in the executable and can be calculated as
"used stack = hunks * 16 + 32"
currently the executable must not contain more than 256 hunks (also
AmigaDOS allows not more than 256 hunks)
the routine performs automatically a resload_FlushCache before
returning
SEE ALSO
WHDLoad/resload_SaveFile
NAME
resload_SaveFile -- write memory to a file
SYNOPSIS
success,errorcode = resload_SaveFile(size, name, address)
D0 D1 D0 A0 A1
BOOL ULONG ULONG CPTR APTR
FUNCTION
write specified memory area to file using specified name
INPUTS
size - amount of bytes to write
name - name of file to write
address - memory address of buffer to write
EXAMPLE
...
move.l #512,d0 ;size
lea (_save,pc),a0 ;name
lea $5ac20,a1 ;source
move.l (_resload,pc),a2
jsr (resload_SaveFile,a2)
...
_save dc.b "saved",0
RESULT
success - TRUE on success
errorcode - 0 on success
otherwise a dos-errorcode from dos.IoErr()
if WHDLF_NoError is set, the function only returns on success
BUGS
NOTE
SEE ALSO
resload_SaveFileOffset
WHDLoad/resload_SaveFileOffset
NAME
resload_SaveFileOffset -- write memory to a file at offset
SYNOPSIS
success,error = resload_SaveFileOffset(size, offset, name, address)
D0 D1 D0 D1 A0 A1
BOOL ULONG ULONG ULONG CPTR APTR
FUNCTION
write specified memory area to file at specified offset using
specified name
INPUTS
size - amount of bytes to write
offset - offset in the file to write
name - name of file to write
address - memory address of buffer to write
EXAMPLE
...
move.l #512,d0 ;size
move.l #$4000,d1 ;offset
lea (_save,pc),a0 ;name
lea $5ac20,a1 ;source
move.l (_resload,pc),a2
jsr (resload_SaveFileOffset,a2)
...
_save dc.b "saved",0
RESULT
success - TRUE on success
errorcode - 0 on success
otherwise a dos-errorcode from dos.IoErr()
if WHDLF_NoError is set, the function only returns on success
BUGS
NOTE
requires ws_Version >= 5
SEE ALSO
resload_SaveFile
WHDLoad/resload_SetCACR
NAME
resload_SetCACR -- set cachebility for BaseMem
SYNOPSIS
old = resload_SetCACR(new, mask)
D0 D0 D1
ULONG ULONG ULONG
FUNCTION
modifies the cachebility for BaseMem, using this routine the
instruction and the data cache can be enabled and disabled,
the changes will affect the CACR (Cache Control Register) and
the MMU-tables if it is used by WHDLoad
INPUTS
new - new cache status
mask - status bits to change
valid values for new and mask are:
CACRF_EnableI - instruction cache
CACRF_EnableD - data cache
(bits are defined in the standard include file "exec/execbase.i")
EXAMPLE
to enable instruction cache:
...
move.l #CACRF_EnableI,d0 ;new status
move.l d0,d1 ;status to change
move.l (_resload,pc),a2
jsr (resload_SetCACR,a2)
...
RESULT
old - old cache status
BUGS
NOTE
it is safe to call this routine from User or Supervisor mode and
independend from the actual CPU type (also on 68000/010)
if WHDLoad is launched with the option NoCache/S this routine will
return without changing anything (BaseMem is always noncacheable)
don't wonder if you see in the coredump or in a freezer that caches
are enabled even if not enabled by the Slave: if the MMU is used by
WHDLoad and no caches are switched on by the Slave, WHDLoad marks the
BaseMem using the MMU as noncacheable-serialized, and enables both
caches so that the memory of WHDLoad and the Slave are cachable to
increase performance
the routine performs automatically a resload_FlushCache before
returning
SEE ALSO
resload_SetCPU, resload_FlushCache
WHDLoad/resload_SetCPU
NAME
resload_SetCPC -- control CPU setup
SYNOPSIS
old = resload_SetCPU(new, mask)
D0 D0 D1
ULONG ULONG ULONG
FUNCTION
change cachebility of memory areas and change the CPU setup
see include file "whdload.i" for supported bit sets
INPUTS
new - new setup
mask - parts of the current setup to change
EXAMPLE
to enable the only instruction cache for BaseMem and ExpMem:
...
move.l #WCPUF_Base_WT|WCPUF_Exp_CB|WCPUF_IC,d0
move.l #WCPUF_Base|WCPUF_Exp|WCPUF_IC|WCPUF_DC,d1
move.l (_resload,pc),a2
jsr (resload_SetCPU,a2)
...
RESULT
old - the setup before
BUGS
NOTE
it is safe to call this routine from User or Supervisor mode and
independend from the actual CPU type (also on 68000/010)
if WHDLoad is launched with the option NoCache/S this routine will
return without changing anything
don't wonder if you see in the coredump or in a freezer that caches
are enabled even if not enabled by the Slave: if the MMU is used by
WHDLoad and no caches are switched on by the Slave, WHDLoad marks the
memory of the installed program using the MMU as noncacheable-
serialized, and enables both caches so that the memory of WHDLoad is
cachable to increase performance
the routine performs automatically a resload_FlushCache before
returning
SEE ALSO
WHDLoad.Slave/--Overview--
The WHDLoad.Slave contains the interface code which makes the installed
program able to load his files from harddisk. Additional it should realize
the possibility to quit the program to return to the OS.
FORMAT
is a standard amiga executable
ATTENTION
the Slave MUST consist of only ONE hunk (ONE section)
the Slave MUST be 100% PC-relative
STRUCTURE
at the top of the Slave is "WHDLoadSlave" structure, after this
follows the specific code and data
STRUCTURE WHDLoadSlave,0
STRUCT ws_Security,4
STRUCT ws_ID,8
UWORD ws_Version
UWORD ws_Flags
ULONG ws_BaseMemSize
ULONG ws_ExecInstall
RPTR ws_GameLoader
RPTR ws_CurrentDir
RPTR ws_DontCache
( LABEL ws_SIZEOF_pre_v4 )
UBYTE ws_keydebug
UBYTE ws_keyexit
( LABEL ws_SIZEOF_pre_v8 )
ULONG ws_ExpMem
( LABEL ws_SIZEOF_pre_v10 )
RPTR ws_name
RPTR ws_copy
RPTR ws_info
LABEL ws_SIZEOF
ws_Security
the code
moveq #-1,d0
rts
to avoid problems if somebody tries execute the Slave directly
ws_ID
the string "WHDLOADS" to identify the program as a Slave
(use the macro SLAVE_HEADER defined in the include file "whdload.i" to
create the entries ws_Security and ws_ID)
ws_Version
the version of WHDLoad that is required by the Slave,
some resload functions need at least a specific version of
WHDLoad, e.g. to use resload_CRC16 you must set ws_Version
to 3 or higher
on the other side the size of the WHDLoadSlave structure
differs for different Slave versions, e.g. if you set
ws_Version to 4 or higher you MUST initialize the fields
ws_keydebug and ws_keyexit and so on
ws_Flags
WHDLF_Disk / WHDLB_Disk
this flag should enabled if the program uses
disk images (the result is a different working Preload/S)
(starting WHDLoad 0.143 this flag is obsolete)
WHDLF_NoError / WHDLB_NoError
if enabled every error occuring in a resload_#? function
lets WHDLoad immedately quit, and prompt an error requester
about the reason
using this flag it is not neccessary that the Slave checks
the return code resload_#? functions, it can be sure that
if a function returns it was successful (this will make the
Slave more simple)
WHDLF_EmulTrap / WHDLB_EmulTrap
this flag has only effect if the VBR is moved by WHDLoad
(i.e. the machine is at least a 68010 and the tooltype
NoVBRMove is not set)
if the flag is set all "trap #0..15"'s are emulated by the
exception handler in WHDLoad like the autovectors, i.e.
the handler checks if the vector ($80-$bc) is initialized
by the program, and if it is the routine will be called by
the handler
WHDLF_NoDivZero / WHDLB_NoDivZero
this flag has only effect if the VBR is moved by WHDLoad
(i.e. the machine is at least a 68010 and the tooltype
NoVBRMove is not set)
if the flag is set and a "Division by Zero" exception
occurs WHDLoad will not quit with an requester, but a
RTE will be performed
this maybe useful if you don't want use the option
NoVBRMove but the demo/game performs divisions by zero
WHDLF_Req68020 / WHDLB_Req68020
this flag indicates that the Slave/installed program
requires at least a MC68020 CPU, WHDLoad will check at
startup if this requirement matches, if it doesn't the
program will be terminated with an appropriate requester
WHDLF_ReqAGA / WHDLB_ReqAGA
this flag indicates that the Slave/installed program
requires at least the AGA chipset, WHDLoad will check at
startup if this requirement matches, if it doesn't the
program will be terminated with an appropriate requester
WHDLF_NoKbd / WHDLB_NoKbd
this flag says WHDLoad, that it doesn't should reply the
keyboard if a key was pressed, this must be used with
programs which doesn't check the keyboard from the PORTS
interrupt ($68), background: in normal operation when
NoVBRMove is inactive, WHDLoad checks if a key was pressed
on each interrupt, if a key has been pressed it checks the
rawkey code against QuitKey, DebugKey and FreezeKey, if it
doesn't match it looks if there is a initialized PORTS
interrupt ($68), if there is no, it replies the keyboard
that the keycode has been received, therefore the installed
program if it checks the keyboard from e.g. the VBI will
never receive any keycode, this flag avoids this behavior
WHDLF_EmulLineA / WHDLB_EmulLineA
this flag has only effect if the VBR is moved by WHDLoad
(i.e. the machine is at least a 68010 and the tooltype
NoVBRMove is not set)
if the flag is set all exceptions "Line-A" (caused by
opcodes starting with %1010) are emulated by the
exception handler in WHDLoad like the autovectors, i.e.
the handler checks if the vector ($28) is initialized
by the program, and if it is the routine which the vector
points to will be called by the handler
WHDLF_EmulTrapV / WHDLB_EmulTrapV
this flag has only effect if the VBR is moved by WHDLoad
(i.e. the machine is at least a 68010 and the tooltype
NoVBRMove is not set)
if the flag is set all exceptions caused by a TrapV
instruction are emulated by the exception handler in
WHDLoad like the autovectors, i.e. the handler checks if
the vector ($1C) is initialized by the program, and if it
is the routine which the vector points to will be called
by the handler
ws_BaseMemSize
the size of the memory that is required by the program
the BaseMemory starts an $00000000 and ends at ws_BaseMemSize
(BaseMemory is always ChipMem)
this value must be multiple of $1000
the valid minimum is $2000, the maximum $200000
ws_ExecInstall
obsolete, must be set to 0
ws_GameLoader
a relative (to the start of the structure) 16-bit pointer
to the start code of the Slave
ws_CurrentDir
a relative (to the start of the structure) 16-bit pointer
to a 0 terminated string which is the name of the path
where all files are stored (sub directory)
if no sub directory is used initialize this with 0
WHDLoad will change into this directory on startup
the path must be relative; you MUST NOT use any fucking lame
assignments
BACKGROUND: if the assignment is not active on runtime the
dos.library will try to show a "Insert Disk ..." requester,
but intuition.library is locked, -> the system will hang
(deadlock) the user has only one alternative -> REBOOT
ws_DontCache
a relative (to the start of the structure) 16-bit pointer
to a 0 terminated string which is a standard AmigaDOS
pattern (dos.ParsePattern, dos.MatchPattern)
all files matching this pattern are not cached by WHDLoad
this may be useful for savegames
if you dont want to use set the entry to 0
starting WHDLoad version 0.107 this is obsolete, because saved
files will be written also to the file cache
the following variables are only evaluated by WHDLoad if ws_Version
is set to >= 4
the following variables MUST be initialized if you set ws_Version
to >= 4
ws_keydebug
the raw key code to exit with debug
this variable will be overwritten by WHDLoad if the option
DebugKey= is set in the global config or as CLI argument or
ToolType with the specified value from there
if the Slave provides an own handler to support a debug option
via the keyboard it should use this entry for comparision, so
it will be possible for the user to change the default key
suggestion from the Slave
this entry is also used by WHDLoad's internal handler if the
VBR is moved (requires 68010+ and that NoVBRMove is not set)
(recommend is $58 = "F9")
ws_keyexit
the raw key code to exit
similar to ws_keydebug
(recommend is $59 = "F10")
the following variables are only evaluated by WHDLoad if ws_Version
is set to >= 8
the following variables MUST be initialized if you set ws_Version
to >= 8
ws_ExpMem
if the installed program requires expansion memory, the size
must be specified here, WHDLoad will allocate a memory block
of this size and writes a pointer to the start of the
allocated memory back to this entry, the memory is granted to
be aligned to $1000 (4096 bytes), the size specified must be
an multiple of $1000 (4096), if WHDLoad fails to allocate
this memory it terminates with an appropriate error requester,
that means the Slave will always get a valid pointer here
- starting WHDLoad version 10.2 the value can be negative,
which means that the memory is optional and not absolute
required, WHDLoad will try to allocate it and if it fails it
will set ws_ExpMem to zero, the Slave has to check ws_ExpMem
therefore
the following variables are only evaluated by WHDLoad if ws_Version
is set to >= 10
the following variables MUST be initialized if you set ws_Version
to >= 10
ws_name
a relative (to the start of the structure) 16-bit pointer
to a 0 terminated string containing the name of the installed
program, e.g. "Super Hang Off"
ws_copy
a relative (to the start of the structure) 16-bit pointer
to a 0 terminated string containing the copyright of the
installed program, the string should start with the year
followed by the company holding the copyright, multiple years
or companies should be separated with ", "
e.g. "1983 Schega, 1989 Bad Dreams"
ws_info
a relative (to the start of the structure) 16-bit pointer
to a 0 terminated string containing addional infos about the
installed program, the string may also contain line feeds
($0a), the character -1 has a special meaning - it results in
a line feed and an additional vertical skip of the half font
height, e.g.:
dc.b "installed & fixed by Wepl",10
dc.b "version 1.4 (06.06.2066)",-1
dc.b "greetings to the world",0
CONVENTIONS for ws_GameLoader
the status of the system at the moment of calling ws_GameLoader:
CPU:
SR = $2000 Supervisor-mode, all interrupts enabled
SSP = ws_BaseMemSize at end of BaseMem
USP = SSP-$400 at end of BaseMem - 1024
A0 = ResidentLoader pointer to the resident Jump-Tower
D0-D7/A1-A6 random (D0=$d0d0d0d0 D1=...)
nothing more is interesting from the Slave programmes point of
view, all special registers like VBR,SFC,DFC,CAAR,CACR,MSP,TC,
MMUSR,CRP,SRP,URP,TT0,TT1,DTT0,DTT1,ITT0,ITT1,PCR,BUSCR are
WHDLoad private and MUST NOT BE CHANGED.
BaseMem:
$00000000 = 0
$00000004 = $f0000001 any try to use the execbase should
create a "Address Error" exception
$00000008 - $00000400
= $CCCCCCCC if WHDLoad has moved the VBR else
= Handler the address of a exception handler
inside WHDLoad
$00000400 - ws_BaseMemSize
= $CCCCCCCC this memory fill pattern is used to
easy recognize modified memory
$00001000 = $FFFFFFFE the copper instruction "CWAIT $ff,$1fe"
ExpMem:
the memory is filled with the pattern "$DDDDDDDD"
custom:
dmacon = 0 all dma's off
intena = 0 all interrupts off
cop1lc = cop2lc = $1000
a AGA-machine is switched to OCS
cia's:
------- ciaa ------ ------- ciab ------
pra in = %00000000 pra in = %00000000
pra out = %11111100 pra out = %11111000
ddra = %00000011 ddra = %11000000
prb in = %00000000 prb in = %00000000
prb out = %00000000 prb out = %11111111
ddrb = %00000000 ddrb = %11111111
ta = $21ff ta = $ffff
tb = $21ff tb = $ffff
event = $000000 event = $000000
alarm = $ffffff alarm = execbase.EClockFrequency
sdr = $00 sdr = $00
icr = %00000000 icr = %00000000
icm = %00001000 icm = %00000000
cra = %00000000 cra = %00000000
crb = %00000000 crb = %00000000
SEE ALSO
example Slaves